<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta name="generator" content="HTML Tidy, see www.w3.org" />

    <title>Manual Page: apxs - Apache HTTP Server</title>
  </head>

  <body bgcolor="#ffffff" text="#000000" link="#0000ff"
  vlink="#000080" alink="#ff0000">
    <!--#include virtual="header.html" -->

    <h1 align="center">Manual Page: apxs</h1>
    <!-- This document was autogenerated from the man page -->
<pre>
<strong>NAME</strong>
     apxs - APache eXtenSion tool

<strong>SYNOPSIS</strong>
     <strong>apxs</strong> -<strong>g</strong> [ -<strong>S</strong> <em>variable</em>=<em>value</em> ] -<strong>n</strong> <em>name</em>

     <strong>apxs</strong> -<strong>q</strong> [ -<strong>S</strong> <em>variable</em>=<em>value</em> ] <em>query</em> ...

     <strong>apxs</strong> -<strong>c</strong> [ -<strong>S</strong> <em>variable</em>=<em>value</em> ] [ -<strong>o</strong> <em>dsofile</em> ] [ -<strong>I</strong> <em>incdir</em> ] [
     -<strong>D</strong>  <em>variable</em>[=<em>value</em>]  ]  [  -<strong>L</strong>  <em>libdir</em>  ]  [  -<strong>l</strong> <em>libname</em> ] [
     -<strong>Wc,</strong><em>compiler</em>-<em>flags</em> ] [ -<strong>Wl,</strong><em>linker</em>-<em>flags</em> ] <em>files</em> ...

     <strong>apxs</strong> -<strong>i</strong> [ -<strong>S</strong> <em>variable</em>=<em>value</em> ] [ -<strong>n</strong> <em>name</em> ] [ -<strong>a</strong> ] [ -<strong>A</strong> ] <em>dso-</em>
     <em>file</em> ...

     <strong>apxs</strong> -<strong>e</strong> [ -<strong>S</strong> <em>variable</em>=<em>value</em> ] [ -<strong>n</strong> <em>name</em> ] [ -<strong>a</strong> ] [ -<strong>A</strong> ] <em>dso-</em>
     <em>file</em> ...

<strong>DESCRIPTION</strong>
     <strong>apxs</strong> is a tool for building and installing extension modules
     for  the  Apache  HyperText Transfer Protocol (HTTP) server.
     This is achieved by building a Dynamic Shared  Object  (DSO)
     from  one  or  more source or object <em>files</em> which then can be
     loaded into the Apache server under runtime via the  <strong>LoadMo-</strong>
     <strong>dule</strong> directive from <strong>mod_so.</strong>

     So to use this extension mechanism,  your  platform  has  to
     support  the DSO feature and your Apache <strong>httpd</strong> binary has to
     be built with the <strong>mod_so</strong> module.  The  <strong>apxs</strong>  tool  automati-
     cally complains if this is not the case.  You can check this
     yourself by manually running the command

       $ httpd -l

     The module <strong>mod_so</strong> should be part of the displayed list.   If
     these requirements are fulfilled, you can easily extend your
     Apache server's functionality by installing your own modules
     with the DSO mechanism by the help of this <strong>apxs</strong> tool:

       $ apxs -i -a -c mod_foo.c
       gcc -fpic -DSHARED_MODULE -I/path/to/apache/include -c mod_foo.c
       ld -Bshareable -o mod_foo.so mod_foo.o
       cp mod_foo.so /path/to/apache/libexec/mod_foo.so
       chmod 755 /path/to/apache/libexec/mod_foo.so
       [activating module `foo' in /path/to/apache/etc/httpd.conf]
       $ apachectl restart
       /path/to/apache/sbin/apachectl restart: httpd not running, trying to start
       [Tue Mar 31 11:27:55 1998] [debug] mod_so.c(303): loaded module foo_module
       /path/to/apache/sbin/apachectl restart: httpd started
       $ _

     The arguments <em>files</em> can be any C source file (.c), a  object
     file  (.o)  or  even  a  library archive (.a). The <strong>apxs</strong> tool
     automatically recognizes these extensions and  automatically
     uses  the  C source files for compilation while it just uses
     the object and archive files for the linking phase. But when
     using such pre-compiled objects, make sure they are compiled
     for Position Independent Code (PIC) to be able to  use  them
     for a DSO. For instance with GCC you always just have to use
     <strong>-fpic</strong>.  For other C compilers please consult its manual page
     or  watch  for  the  flags  <strong>apxs</strong>  uses to compile the object
     files.

     For more details about DSO support in Apache, first read the
     background  information about DSO in htdocs/manual/dso.html,
     then read the documentation of <strong>mod_so</strong>.

<strong>OPTIONS</strong>
     Common options:

     -<strong>n</strong> <em>name  </em>   This explicitly sets the module name for the  -<strong>i</strong>
                 (install)  and  -<strong>g</strong> (template generation) option.
                 Use this to explicitly specify the module  name.
                 For  option  -<strong>g</strong>  this is required, for option -<strong>i</strong>
                 the <strong>apxs</strong> tool tries to determine the  name  from
                 the source or (as a fallback) at least by guess-
                 ing it from the filename.

     Query options:

     -<strong>q       </strong>   Performs a query for <strong>apxs</strong>'s knowledge about cer-
                 tain  settings.  The <em>query</em> parameters can be one
                 or more of the following variable names:
                   CC              TARGET
                   CFLAGS          SBINDIR
                   CFLAGS_SHLIB    INCLUDEDIR
                   LD_SHLIB        LIBEXECDIR
                   LDFLAGS_SHLIB   SYSCONFDIR
                   LIBS_SHLIB      PREFIX
                 Use this for manually determining settings.  For
                 instance use
                   INC=-I`apxs -q INCLUDEDIR`
                 inside your own Makefiles  if  you  need  manual
                 access to Apache's C header files.

     Configuration options:

     -<strong>S</strong> <em>variable</em>=<em>value</em>
                 This option changes the <strong>apxs</strong> settings  described
                 above.

     Template Generation options:
     -<strong>g       </strong>   This generates a subdirectory <em>name</em>  (see  option
                 -<strong>n</strong>)  and there two files: A sample module source
                 file named <strong>mod_</strong><em>name</em>.<em>c</em> which can  be  used  as  a
                 template  for  creating your own modules or as a
                 quick start for playing with the <strong>apxs</strong> mechanism.
                 And  a  corresponding  <strong>Makefile</strong>  for even easier
                 building and installing of this module.

     DSO compilation options:

     -<strong>c       </strong>   This indicates  the  compilation  operation.  It
                 first  compiles the C source files (.c) of <em>files</em>
                 into corresponding object files  (.o)  and  then
                 builds  a DSO in <em>dsofile</em> by linking these object
                 files plus the remaining object  files  (.o  and
                 .a)  of  <em>files</em>  If no -<strong>o</strong> option is specified the
                 output file is guessed from the  first  filename
                 in   <em>files</em>   and   thus   usually   defaults  to
                 <strong>mod_</strong><em>name</em>.<em>so</em>

     -<strong>o</strong> <em>dsofile</em>  Explicitly specifies the filename of the created
                 DSO  file.  If not specified and the name cannot
                 be guessed from the  <em>files</em>  list,  the  fallback
                 name <strong>mod_unknown.so</strong> is used.

     -<strong>D</strong> <em>variable</em>[=<em>value</em>]
                 This option is directly passed  through  to  the
                 compilation  command(s).   Use  this to add your
                 own defines to the build process.

     -<strong>I</strong> <em>incdir</em>   This option is directly passed  through  to  the
                 compilation  command(s).   Use  this to add your
                 own include directories to search to  the  build
                 process.

     -<strong>L</strong> <em>libdir</em>   This option is directly passed  through  to  the
                 linker  command.   Use  this  to  add  your  own
                 library directories to search to the build  pro-
                 cess.

     -<strong>l</strong> <em>libname</em>  This option is directly passed  through  to  the
                 linker  command.   Use  this  to  add  your  own
                 libraries to search to the build process.

     -<strong>Wc,</strong><em>compiler</em>-<em>flags</em>
                 This option passes <em>compiler</em>-<em>flags</em> as  additional
                 flags  to the compiler command.  Use this to add
                 local compiler-specific options.

     -<strong>Wl,</strong><em>linker</em>-<em>flags</em>
                 This option passes  <em>linker</em>-<em>flags</em>  as  additional
                 flags  to  the  linker command.  Use this to add
                 local linker-specific options.

     DSO installation and configuration options:

     -<strong>i       </strong>   This indicates the  installation  operation  and
                 installs  one  or  more  DSOs  into the server's
                 <em>libexec</em> directory.

     -<strong>a       </strong>   This  activates  the  module  by   automatically
                 adding   a   corresponding  <strong>LoadModule</strong>  line  to
                 Apache's <strong>httpd.conf</strong> configuration  file,  or  by
                 enabling it if it already exists.

     -<strong>A       </strong>   Same as option -<strong>a</strong>  but  the  created  <strong>LoadModule</strong>
                 directive is prefixed with a hash sign (#), i.e.
                 the module is just prepared for later activation
                 but initially disabled.

     -<strong>e       </strong>   This indicates the editing operation, which  can
                 be  used with the -<strong>a</strong> and -<strong>A</strong> options similarly to
                 the -<strong>i</strong> operation  to  edit  Apache's  <strong>httpd.conf</strong>
                 configuration file without attempting to install
                 the module.

<strong>EXAMPLES</strong>
     Assume you have an Apache module named  mod_foo.c  available
     which should extend Apache's server functionality. To accom-
     plish this you first have to compile the C source into a DSO
     suitable  for  loading  into the Apache server under runtime
     via the following command:

       $ apxs -c mod_foo.c
       gcc -fpic -DSHARED_MODULE -I/path/to/apache/include -c mod_foo.c
       ld -Bshareable -o mod_foo.so mod_foo.o
       $ _

     Then you have to update the Apache configuration  by  making
     sure  a <strong>LoadModule</strong> directive is present to load this DSO. To
     simplify this step <strong>apxs</strong> provides an automatic way to install
     the   DSO  in  the  "libexec"  directory  and  updating  the
     <strong>httpd.conf</strong> file accordingly. This can be  achieved  by  run-
     ning:

       $ apxs -i -a mod_foo.c
       cp mod_foo.so /path/to/apache/libexec/mod_foo.so
       chmod 755 /path/to/apache/libexec/mod_foo.so
       [activating module `foo' in /path/to/apache/etc/httpd.conf]
       $ _

     This way a line named

       LoadModule foo_module libexec/mod_foo.so

     is added to the configuration file if still not present.  If
     you  want  to have this operation to be disabled, use the -<strong>A</strong>
     option, i.e.

       $ apxs -i -A mod_foo.c

     For a quick test of the <strong>apxs</strong> mechanism you can create a sam-
     ple  Apache  module  template  plus a corresponding <strong>Makefile</strong>
     via:

       $ apxs -g -n foo
       Creating [DIR]  foo
       Creating [FILE] foo/Makefile
       Creating [FILE] foo/mod_foo.c
       $ _

     Then you can immediately compile this sample module  into  a
     DSO and load it into the Apache server:

       $ cd foo
       $ make all reload
       apxs -c mod_foo.c
       gcc -fpic -DSHARED_MODULE -I/path/to/apache/include -c mod_foo.c
       ld -Bshareable -o mod_foo.so mod_foo.o
       apxs -i -a -n "foo" mod_foo.so
       cp mod_foo.so /path/to/apache/libexec/mod_foo.so
       chmod 755 /path/to/apache/libexec/mod_foo.so
       [activating module `foo' in /path/to/apache/etc/httpd.conf]
       apachectl restart
       /path/to/apache/sbin/apachectl restart: httpd not running, trying to start
       [Tue Mar 31 11:27:55 1998] [debug] mod_so.c(303): loaded module foo_module
       /path/to/apache/sbin/apachectl restart: httpd started
       $ _

     You can even use <strong>apxs</strong> to compile complex modules outside the
     Apache  source  tree,  like PHP3, because <strong>apxs</strong> automatically
     recognized C source files and object files.

       $ cd php3
       $ ./configure --with-shared-apache=../apache-1.3
       $ apxs -c -o libphp3.so mod_php3.c libmodphp3-so.a
       gcc -fpic -DSHARED_MODULE -I/tmp/apache/include  -c mod_php3.c
       ld -Bshareable -o libphp3.so mod_php3.o libmodphp3-so.a
       $ _

     Only C source files  are  compiled  while  remaining  object
     files are used for the linking phase.

<strong>SEE ALSO</strong>
     <strong>apachectl(1), httpd(8).</strong>

</pre>
    <!--#include virtual="footer.html" -->
  </body>
</html>

